001 /* 002 * Copyright 2001-2005 Stephen Colebourne 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 package org.joda.time; 017 018 /** 019 * Defines a partial time that does not support every datetime field, and is 020 * thus a local time. 021 * <p> 022 * A <code>ReadablePartial</code> supports a subset of those fields on the chronology. 023 * It cannot be compared to a <code>ReadableInstant</code>, as it does not fully 024 * specify an instant in time. The time it does specify is a local time, and does 025 * not include a time zone. 026 * <p> 027 * A <code>ReadablePartial</code> can be converted to a <code>ReadableInstant</code> 028 * using the <code>toDateTime</code> method. This works by providing a full base 029 * instant that can be used to 'fill in the gaps' and specify a time zone. 030 * 031 * @author Stephen Colebourne 032 * @since 1.0 033 */ 034 public interface ReadablePartial { 035 036 /** 037 * Gets the number of fields that this partial supports. 038 * 039 * @return the number of fields supported 040 */ 041 int size(); 042 043 /** 044 * Gets the field type at the specified index. 045 * 046 * @param index the index to retrieve 047 * @return the field at the specified index 048 * @throws IndexOutOfBoundsException if the index is invalid 049 */ 050 DateTimeFieldType getFieldType(int index); 051 052 /** 053 * Gets the field at the specified index. 054 * 055 * @param index the index to retrieve 056 * @return the field at the specified index 057 * @throws IndexOutOfBoundsException if the index is invalid 058 */ 059 DateTimeField getField(int index); 060 061 /** 062 * Gets the value at the specified index. 063 * 064 * @param index the index to retrieve 065 * @return the value of the field at the specified index 066 * @throws IndexOutOfBoundsException if the index is invalid 067 */ 068 int getValue(int index); 069 070 /** 071 * Gets the chronology of the partial which is never null. 072 * <p> 073 * The {@link Chronology} is the calculation engine behind the partial and 074 * provides conversion and validation of the fields in a particular calendar system. 075 * 076 * @return the chronology, never null 077 */ 078 Chronology getChronology(); 079 080 /** 081 * Gets the value of one of the fields. 082 * <p> 083 * The field type specified must be one of those that is supported by the partial. 084 * 085 * @param field a DateTimeFieldType instance that is supported by this partial 086 * @return the value of that field 087 * @throws IllegalArgumentException if the field is null or not supported 088 */ 089 int get(DateTimeFieldType field); 090 091 /** 092 * Checks whether the field type specified is supported by this partial. 093 * 094 * @param field the field to check, may be null which returns false 095 * @return true if the field is supported 096 */ 097 boolean isSupported(DateTimeFieldType field); 098 099 /** 100 * Converts this partial to a full datetime by resolving it against another 101 * datetime. 102 * <p> 103 * This method takes the specified datetime and sets the fields from this 104 * instant on top. The chronology from the base instant is used. 105 * <p> 106 * For example, if this partial represents a time, then the result of this 107 * method will be the datetime from the specified base instant plus the 108 * time from this partial. 109 * 110 * @param baseInstant the instant that provides the missing fields, null means now 111 * @return the combined datetime 112 */ 113 DateTime toDateTime(ReadableInstant baseInstant); 114 115 //----------------------------------------------------------------------- 116 /** 117 * Compares this partial with the specified object for equality based 118 * on the supported fields, chronology and values. 119 * <p> 120 * Two instances of ReadablePartial are equal if they have the same 121 * chronology, same field types (in same order) and same values. 122 * 123 * @param partial the object to compare to 124 * @return true if equal 125 */ 126 boolean equals(Object partial); 127 128 /** 129 * Gets a hash code for the partial that is compatible with the 130 * equals method. 131 * <p> 132 * The formula used must be: 133 * <pre> 134 * int total = 157; 135 * for (int i = 0; i < fields.length; i++) { 136 * total = 23 * total + values[i]; 137 * total = 23 * total + fieldTypes[i].hashCode(); 138 * } 139 * total += chronology.hashCode(); 140 * return total; 141 * </pre> 142 * 143 * @return a suitable hash code 144 */ 145 int hashCode(); 146 147 // NOTE: This method should have existed in Joda-Time v1.0. 148 // We STRONGLY recommend that all implementations of ReadablePartial 149 // implement this method, as per AbstractPartial. 150 // The simplest way to do this is to extend AbstractPartial. 151 // v2.0 of Joda-Time will include this method in this interface. 152 // //----------------------------------------------------------------------- 153 // /** 154 // * Compares this partial with another returning an integer 155 // * indicating the order. 156 // * <p> 157 // * The fields are compared in order, from largest to smallest. 158 // * The first field that is non-equal is used to determine the result. 159 // * Thus a YearHour partial will first be compared on the year, and then 160 // * on the hour. 161 // * <p> 162 // * The specified object must be a partial instance whose field types 163 // * match those of this partial. If the parial instance has different 164 // * fields then a ClassCastException is thrown. 165 // * 166 // * @param partial an object to check against 167 // * @return negative if this is less, zero if equal, positive if greater 168 // * @throws ClassCastException if the partial is the wrong class 169 // * or if it has field types that don't match 170 // * @throws NullPointerException if the partial is null 171 // * @since 2.0 172 // */ 173 // int compareTo(Object partial); 174 175 //----------------------------------------------------------------------- 176 /** 177 * Get the value as a String in a recognisable ISO8601 format, only 178 * displaying supported fields. 179 * <p> 180 * The string output is in ISO8601 format to enable the String 181 * constructor to correctly parse it. 182 * 183 * @return the value as an ISO8601 string 184 */ 185 String toString(); 186 187 }